Principled GraphQL
概要
https://principledgraphql.com/static/fa53fbb1d02c0167a5fadff64825f882/20107/overview.png
Apollo によって、Principled GraphQL という記事が公開された。これは、Apollo が 2015 年からデータグラフ技術を先導してきてからのこの数年間、大小含めた企業に属する様々な GraphQL 開発者と議論を重ねてきた中で得た知見を共有するもの、とされている。記事は GitHub でもオープンに管理されているので、PR や issue も送れそうだ。
ここでは要点だけメモをしておく
Integrity Principles (統一の原則)
1. One Graph
企業は、チーム毎に作成された複数のグラフではなく、統合された１つのグラフ をもつべき
メリット:
1 回のクエリで、より多くのデータやサービスにアクセスできるようになる
コード、クエリ、スキル、経験が、チーム横断的に活用できる
1 つのグラフが、利用可能な全てのデータのカタログになる
グラフの実装作業が重複しないので、実装コストが最小化される
グラフの中央管理 (アクセス制御ポリシーを統一する、等) が可能になる
グラフを統一しないことによるデメリット:
チーム間で統率が取れず、グラフがオーバーラップし、同じデータを異なる方法でグラフに表現し、最悪カオスに陥る
2. Federated Implementation
組織の統一されたグラフを１つのコードベースで管理せず、グラフの定義, 実装の責務はチーム間に分散 させる
各チームは、彼らのデータやサービスを露出させるスキーマについてはメンテする責務を負う
各チームは、独自に開発して独自にリリースサイクルを回す柔軟性をもつ
3. Track the Schema in a Registry
グラフの Single source of truth が存在すべき
グラフの正式な定義がどこかに常に公開されており、それを参照できるようになっていることが重要
開発者ツール、ワークフロー、ビジネスプロセス支援のためのハブにする
Agility Principles (敏捷さの原則)
4. Abstract, Demand-Oriented Schema
特定のサービス実装 に密結合させない
スキーマに影響を与えずにサービスのリファクタリングできる
特定のコンシューマ に密結合させない
特定のアプリがデータを取得する方法を密結合すべきでない (再利用性が低まる)
要求指向スキーマ (demand-oriented schema)
5. Use an Agile Approach to Schema Development
早い段階で「完璧なスキーマ」を定義しようとしない
ユーザのニーズに合わせて容易にグラフを進化させていく
フィールドを 推測で 追加しない
コンシューマの具体的なニーズに基づいて追加すべき
グラフは 継続的に更新 する
半年から一年に一度のバージョンアップではなく、必要であれば日になんども行われる ものであるべき
6. Iteratively Improve Performance
グラフの全ての利用方法を最適化するのではなく、プロダクションで 実際に利用されているクエリのサポートに集中する
クエリの構造が変化する場合、ツールがそれを抽出し、影響のあるチームに伝える
本番デプロイされたクエリは、継続的にモニタリングする
7. USe Graph Metadata to Empower Developers
開発者が開発している際には、ツールのサポートによって、常に最新の情報に触れられるようにしておくべき
GraphQL が、フロント/バックエンドチームを結ぶ基本構造になるようにする
data-graph-aware tool のメリット例:
エディタ上で最新のドキュメントとともに利用可能な全てのデータを常に参照できる
フィールドが deprecated になった場合は、それを利用している開発者がエディタ上でそれに気づけ、代替もサジェストされる
本番環境のデータに基づいて、開発者がクエリをエディタに入力した際に、その見積もりコストが表示される
運用チームは、利用者のアプリ、バージョン、機能、コード行まで追跡して、どのようにグラフが利用されているかを完全に把握できる
...
Operations Principles (運用の原則)
8. Access and Demand Control
Authorization (認可)
Access Control ユーザがアクセスできるオブジェクトやフィールドを決定する
Demand Control ユーザがリソースにアクセスする方法やその量を制限する
Authentication (認証)
「操作を要求するアプリケーション」と「アプリケーションを利用するユーザ」という２つの側面
アクセス制御は、ユーザが中心となる
一方、どのような形のクエリを投げるかはアプリケーション、ひいてはアプリケーションの開発者に責任があるため、要求制御ではユーザと同様に、アプリ自体も考慮する必要がある
要求制御のベストプラクティス
クライアントサイドのクエリの広範囲な承認ワークフローを設け、本番投入前にクエリを吟味する
クエリの実行前にクエリのコストを見積もり、ユーザ毎アプリ毎のクエリコスト予算を設定する
緊急時のために、開発者は特定アプリが特定のクエリを送信できないように制限する仕組みを用意しておく
9. Structured Logging
グラフ操作の記録は、トレースと呼ばれる
ビジネス情報 操作を誰が実行したか、クエリかミューテーションか、成功したか、実行方法はどうか
技術情報 どのバックエンドサービスにアクセスしたか、レイテンシーはどうだったか、キャッシュが使用されたか
トレースの活用:
deprecated なフィールドを削除できるかどうか？削除できない場合にはそれを利用しているクライアントはどれか？見つける
本番データを活用してクエリ実行にどの程度かかるか見積もり、開発者の IDE に反映する
レイテンシーやエラーレート等の問題を発見し原因を究明する
ビジネスの強化 (暑い時によくアイスクリームが売れているか？)
アクセスされたフィールドや消費されたリソースに基づいてコストモデルを作成し、パートナーにむけて請求書を作成する
全てのグラフ操作のトレースは一箇所にまとめておき、他の監視システムにエクスポートできるようにしておく
10. Separate the GraphQL Layer from the Service Layer
既存の API 技術
サーバとクライアントは、直接対話しない
ロードバランサー、キャッシュ、サービスロケーション、APIキー管理、...
各層は、独立して設計・運用・拡張が可能
GraphQL
既存の API 技術と変わらず、データグラフに必要な機能毎に層として分離した方が良い
アクセス/要求制御、トレースの収集、キャッシング、...
いくつかの層には GraphQL の深い知識が必要だが、負荷分散や認証については既存システムが利用できるかもしれない